crypto: add uuidv7 monotonic counter by araujogui · Pull Request #62601 · nodejs/node

araujogui · 2026-04-05T16:15:41Z

Follow up #62553

nodejs-github-bot · 2026-04-05T16:15:46Z

Review requested:

@nodejs/crypto

Copilot

Pull request overview

Adds a monotonic counter to crypto.randomUUIDv7() so UUIDv7 values are strictly increasing even when multiple UUIDs are generated within the same millisecond.

Changes:

Implement monotonic rand_a counter state for UUIDv7 generation (buffered + unbuffered paths).
Write timestamp + counter into UUIDv7 bytes before serialization.
Tighten/extend tests to assert strict ordering, including burst generation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
test/parallel/test-crypto-randomuuidv7.js	Updates ordering assertions to require strict monotonic UUID string ordering and adds a burst test.
lib/internal/crypto/random.js	Adds UUIDv7-specific buffered state and monotonic timestamp/counter logic used by `randomUUIDv7()`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-05T16:19:22Z

test/parallel/test-crypto-randomuuidv7.js

 {
  let prev = randomUUIDv7();
  for (let i = 0; i < 100; i++) {
    const curr = randomUUIDv7();
-    // UUIDs with later timestamps must sort after earlier ones.
-    // Within the same millisecond, ordering depends on random bits,
-    // so we only assert >= on the timestamp portion.
-    const prevTs = parseInt(prev.replace(/-/g, '').slice(0, 12), 16);
-    const currTs = parseInt(curr.replace(/-/g, '').slice(0, 12), 16);
-    assert(currTs >= prevTs,
-           `Timestamp went backwards: ${currTs} < ${prevTs}`);
+    // With a monotonic counter in rand_a, each UUID must be strictly greater
+    // than the previous regardless of whether the timestamp changed.
+    assert(curr > prev,
+           `UUID ordering violated: ${curr} <= ${prev}`);
    prev = curr;
  }
 }

+// Sub-millisecond ordering: a tight synchronous burst exercises the counter
+// increment path and must also produce strictly increasing UUIDs.
+{
+  const burst = [];
+  for (let i = 0; i < 500; i++) {
+    burst.push(randomUUIDv7());
+  }
+  for (let i = 1; i < burst.length; i++) {
+    assert(burst[i] > burst[i - 1],
+           `Sub-millisecond ordering violated at index ${i}: ` +
+           `${burst[i]} <= ${burst[i - 1]}`);
+  }
+}


The new monotonic-ordering assertions only exercise the default (buffered) code path. Since this PR changes both buffered and disableEntropyCache: true (unbuffered) implementations, it would be good to add at least one ordering check for randomUUIDv7({ disableEntropyCache: true }) as well, to ensure the unbuffered counter/timestamp logic stays monotonic too.

harimm · 2026-04-05T17:17:27Z

Can you confirm that it’s intentional for advanceV7() to let the encoded timestamp move ahead of current clock time in order to preserve strict monotonic ordering once the 12-bit space is exhausted within a millisecond? Relatedly, under sustained high-throughput generation across multiple consecutive milliseconds, should we expect that drift from wall clock to continue accumulating until the burst subsides? Out of curiosity, is the 12-bit limit here driven strictly by any spec, or was there any consideration of alternative approaches once that per-millisecond space is exhausted?

codecov · 2026-04-05T17:36:34Z

Codecov Report

❌ Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.81%. Comparing base (dec5973) to head (c798973).
⚠️ Report is 31 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/crypto/random.js	94.02%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62601      +/-   ##
==========================================
+ Coverage   89.70%   89.81%   +0.10%     
==========================================
  Files         695      697       +2     
  Lines      214524   215823    +1299     
  Branches    41080    41293     +213     
==========================================
+ Hits       192443   193844    +1401     
+ Misses      14121    14097      -24     
+ Partials     7960     7882      -78

Files with missing lines	Coverage Δ
lib/internal/crypto/random.js	`95.78% <94.02%> (-0.29%)`	⬇️

... and 57 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

alexsch01 · 2026-04-08T15:30:43Z

If this gets merged, #62600 should get reversed

panva

#62553 (comment)
That can be a follow-up. It would reduce the UUID entropy so would probably need to be optional.

If this gets merged, #62600 should get reversed

In making this optional and documenting it it can also describe the nuance in the docs.

araujogui · 2026-04-08T16:06:53Z

#62553 (comment)
That can be a follow-up. It would reduce the UUID entropy so would probably need to be optional.

If this gets merged, #62600 should get reversed

In making this optional and documenting it it can also describe the nuance in the docs.

Why do you think it should be optional?

panva · 2026-04-08T16:30:34Z

Why do you think it should be optional?

First of all I don't think this is needed in the first place. Second, as @Renegade334's original comment that I've quoted says

It would reduce the UUID entropy so would probably need to be optional.

¯_(ツ)_/¯

panva · 2026-04-09T11:54:31Z

lib/internal/crypto/random.js

    validateObject(options, 'options');
  const {
    disableEntropyCache = false,
+    monotonic = true,


Suggested change

monotonic = true,

monotonic = false,

araujogui · 2026-04-09T11:57:11Z

Why do you think it should be optional?

First of all I don't think this is needed in the first place. Second, as @Renegade334's original comment that I've quoted says

It would reduce the UUID entropy so would probably need to be optional.

I agree and made it optional via an argument, but I don't agree it's not needed, there's a lot of use cases where a counter is critical.

The most used UUID v7 library does this: https://github.com/LiosK/uuidv7/blob/main/src/index.ts#L263

crypto: add uuidv7 monotonic counter

5e312c1

Copilot AI review requested due to automatic review settings April 5, 2026 16:15

nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. needs-ci PRs that need a full CI run. labels Apr 5, 2026

Copilot started reviewing on behalf of araujogui April 5, 2026 16:16 View session

Copilot AI reviewed Apr 5, 2026

View reviewed changes

crypto: fix flaky test

19bb93c

theoludwig mentioned this pull request Apr 7, 2026

doc: note non-monotonic clock in crypto.randomUUIDv7 #62600

Merged

panva previously requested changes Apr 8, 2026

View reviewed changes

crypto: make monotonic counter optional

a5f3be5

panva reviewed Apr 9, 2026

View reviewed changes

araujogui added 2 commits April 9, 2026 09:01

crypto: disable monotonic counter by default

2f90718

crypto: add monotonic counter doc

c798973

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

crypto: add uuidv7 monotonic counter#62601

crypto: add uuidv7 monotonic counter#62601
araujogui wants to merge 5 commits intonodejs:mainfrom
araujogui:uuidv7-counter

araujogui commented Apr 5, 2026

Uh oh!

nodejs-github-bot commented Apr 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 5, 2026

Uh oh!

harimm commented Apr 5, 2026

Uh oh!

codecov bot commented Apr 5, 2026 •

edited

Loading

Uh oh!

alexsch01 commented Apr 8, 2026

Uh oh!

panva left a comment •

edited

Loading

Uh oh!

araujogui commented Apr 8, 2026

Uh oh!

panva commented Apr 8, 2026

Uh oh!

panva Apr 9, 2026

Uh oh!

araujogui commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Conversation

araujogui commented Apr 5, 2026

Uh oh!

nodejs-github-bot commented Apr 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

harimm commented Apr 5, 2026

Uh oh!

codecov bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

alexsch01 commented Apr 8, 2026

Uh oh!

panva left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

araujogui commented Apr 8, 2026

Uh oh!

panva commented Apr 8, 2026

Uh oh!

panva Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

araujogui commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov bot commented Apr 5, 2026 •

edited

Loading

panva left a comment •

edited

Loading